---
title: "Set up Development Environment"
---

```mdx-code-block
import {useState} from 'react';

export const RepositoryOpener = () => {
  const [value, setValue] = useState(0);
  const repoUrl = `vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=${encodeURIComponent(value)}`;
  return <div>
    <input onInput={(ev) => setValue(ev.target.value)} style={{width: "80%", display: "inline-block", marginRight: 16}} />
    <a href={repoUrl}><button style={{cursor: value == "" ? "default" : "pointer"}} disabled={value == ""}>Open</button></a>
  </div>
}
```

You'll need to set up a development environment if you want to develop a new feature or component for Home Assistant. Read on to learn how to set up.

## Developing with Visual Studio Code + devcontainer

The easiest way to get started with development is to use Visual Studio Code with devcontainers. This approach will create a preconfigured development environment with all the tools you need. This approach is enabled for all Home Assistant repositories. [Learn more about devcontainers.](https://code.visualstudio.com/docs/devcontainers/containers)

:::note
As this approach uses containers, you may face challenges exposing hardware like USB devices & adapters (onboard Bluetooth, Zigbee, ...) into the container for testing. This is possible when developing on a Linux host; however, you cannot directly access such hardware if you are using a Windows or MacOS computer for development.
:::

**Prerequisites**

- [Docker](https://docs.docker.com/get-docker/)
- [Visual Studio code](https://code.visualstudio.com/)
- [Git](https://git-scm.com/)

**Getting started:**

1. Go to [Home Assistant core repository](https://github.com/home-assistant/core) and click "fork".
2. Once your fork is created, copy the URL of your fork and paste it below, then click "Open":
   <RepositoryOpener />
3. Your browser will prompt you if you want to use Visual Studio Code to open the link, click "Open Link".
4. When Visual Studio Code asks if you want to install the Remote extension, click "Install".
5. The Dev Container image will then be built (this may take a few minutes), after this your development environment will be ready.
6. You can verify that your dev container is set up properly by the following:
    * Open the command palette in Visual Studio Code - `Shift`+`Command`+`P`(Mac) / `Ctrl`+`Shift`+`P` (Windows/Linux).
    * Select `Tasks: Run Task` -> `Run Home Assistant Core`
    * A terminal should open and begin outputting activity. Check for errors and wait for the output to stop/slow down.
    * Navigate a web browser to `http://localhost:8123`, and you should see the Home Assistant setup screen.

In the future, if you want to get back to your development environment: open Visual Studio Code, click on the "Remote Explorer" button in the sidebar, select "Containers" at the top of the sidebar.

### Tasks

The devcontainer comes with some useful tasks to help you with development, you can start these tasks by opening the command palette with `Shift`+`Command`+`P`(Mac) / `Ctrl`+`Shift`+`P` (Windows/Linux) and select `Tasks: Run Task` then select the task you want to run.

When a task is currently running (like `Preview` for the docs), it can be restarted by opening the command palette and selecting `Tasks: Restart Running Task`, then select the task you want to restart.

### Debugging with Visual Studio Code

If the Dev Container was set up correctly - it supports debugging by default, out-of-the-box. It provides the necessary debug configurations, so hitting F5 should launch Home Assistant. Any breakpoints put in the code should be triggered, and the debugger should stop. 

:::note
If debugging of tests fails with the built-in `pytest` adapter with:

```text
vscode_pytest.VSCodePytestError: Error attempting to connect to extension communication socket[vscode-pytest]: A test tried to use socket.socket.
```

- Open `vscode` with Visual Studio Code and open the Home Assistant Dev Container.
- Open the command palette with: `Ctrl` + `Shift` + `P`
- Type `settings` command then select `>Preferences: Open Remote Settings (JSON) (Dev Container: Home Assistant Dev)`.
- Add `"python.experiments.optOutFrom": ["pythonTestAdapter"]` to the `settings.json` file.
- Restart the Dev Container to ensure the changes are effective.

```json
{
  ...,
  "python.experiments.optOutFrom": ["pythonTestAdapter"]
}
```

:::

It is also possible to debug a remote Home Assistance instance (e.g., production instance) by following the procedure described [here](https://www.home-assistant.io/integrations/debugpy/).

## Manual Environment

_You only need these instructions if you do not want to use devcontainers._

It is also possible to set up a more traditional development environment. See the section for your operating system. Make sure your Python version is 3.11.

### Developing on Linux

Install the core dependencies.

```shell
sudo apt-get update
sudo apt-get install python3-pip python3-dev python3-venv autoconf libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev zlib1g-dev pkg-config libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev ffmpeg
```

### Developing on Windows

To develop on Windows, you will need to use the Linux subsystem (WSL). Follow the [WSL installation instructions](https://learn.microsoft.com/windows/wsl/install) and install Ubuntu from the Windows Store. Once you're able to access Linux, follow the Linux instructions.

:::tip
If you find that you cannot open the development instance via <http://localhost:8123> when using WSL, instead, within a WSL terminal, find the `inet` address of the `eth0` adaptor by running `ip addr show eth0`. Then use this address, excluding the CIDR block, to access the development instance, i.e. if your `inet` is listed as `172.20.37.6/20`, use <http://172.20.37.6:8123>.
:::

#### Freshly installed WSL distribution

The first time a WSL distribution is started, and the default WSL user account is created, the Windows drives will still be mounted with all files owned by `root:root` instead of owned by the default user, i.e. with `uid=0,gid=0` included in the mount options as shown by:

```bash
user@DESKTOP:/mnt/c/Users/user$ mount | grep mnt
C:\ on /mnt/c type drvfs (rw,noatime,uid=0,gid=0,case=off)
```

This will cause the `setup` script to fail with an unrelated error if the local repository is on a Windows drive. To recover, WSL must be restarted after which the Windows drives will be mounted with all files owned by the default WSL user. This can be accomplished by simply restarting the computer, or by issuing the following command from a windows command prompt:

```bash
wsl --shutdown
```

After WSL is restarted, the mount's uid and gid will match the default user.

### Developing on macOS

Install [Homebrew](https://brew.sh/), then use that to install the dependencies:

```shell
brew install python3 autoconf ffmpeg cmake make
```

If you encounter build issues with `cryptography` when running the `script/setup` script below, check the cryptography documentation for [installation instructions](https://cryptography.io/en/latest/installation/#building-cryptography-on-macos).

## Setup Local Repository

Visit the [Home Assistant Core repository](https://github.com/home-assistant/core) and click **Fork**.
Once forked, setup your local copy of the source using the commands:

```shell
git clone https://github.com/YOUR_GIT_USERNAME/core.git
cd core
git remote add upstream https://github.com/home-assistant/core.git
```

Install the requirements with a provided script named `setup`.

```shell
script/setup
```

This will create a virtual environment and install all necessary requirements. You're now set!

Each time you start a new terminal session, you will need to activate your virtual environment:

```shell
source venv/bin/activate
```

After that you can run Home Assistant like this:

```shell
hass -c config
```

If you encounter a crash (`SIGKILL`) while running this command on *macOS*, it's probably about lack of Bluetooth permission. You can fix it by adding this permission for your Terminal app (System Preferences -> Security & Privacy -> Bluetooth).

The Home Assistant configuration is stored in the `config` directory in your repository.
